Detailed Description

template<typename R>
class Quaternion< R >

Quaternions extend complex numbers to dimension 4.

http://en.wikipedia.org/wiki/Quaternion

The unit bases of the Quaternion space are called 1, i, j and k. A quaternion is therefore q[0] + i * q[1] + j * q[2] + k * q[3], where q[?] are four real scalars. q[0] is the real part, and the other parts are imaginary.

While addition is standard, multiplication is anti-commutative:

i*i = -1,
i*j = k,
j*i = -k,
etc,

Unit quaternions are handy to represent rotations in 3D space: The group of 3D rotations has three degrees of freedom, and is mapped directly onto the quaternions of norm 1.

A rotation is represented by a symmetric matrix using 6 scalar numbers, but only 4 scalars are used when a Quaternion is used. Thus one economize spurious scalars, and moreover quaternions are easier to normalize than rotation matrices as necessary to correct for numerical errors.

The rotation associated to a unit quaternion Q is:

v -> Q.v.inv(Q)

where the imaginary quaternion v = { 0, x, y, z } represents a 3D vector { x, y, z }.

Note that it is more costly to calculate a rotated vector using this formula than with a 3x3 matrix-vector multiplication.

The composition of two rotations thus corresponds to quaternion multiplication. For example, Q*P corresponds to the rotation P followed by the rotation Q.

The angle A of the rotation associated with the quaternion Q obeys:

real part of Q = cos(A/2),
norm of imaginary part of Q = sin(a/2). The rotation axis is defined by the imaginary components of Q.

Quaternion<real> implements the standard mathematical operations, conversions to and from 3x3 real matrices, and to 4x4 transformation matrices used in OpenGL.

Public Member Functions
	Quaternion ()
	The default constructor does not reset any value.

	Quaternion (R a, R b, R c, R d)
	Constructor which can be used to convert from a real.

	~Quaternion ()
	Destructor (ATTENTION: non-virtual: do not derive from this class)

void	set (R a, R b, R c, R d)
	setting the values from Cartesian coordinates

R &	operator[] (const int n)
	access to a modifiable coordinate

R	operator[] (const int n) const
	access to a non-modifiable coordinate

	operator R * ()
	conversion operator to a "real array"

R *	addr ()
	conversion to a 'real array'

Quaternion	operator- () const
	opposition: change sign in all coordinates

Quaternion	operator* (R f) const
	multiply by a real value

Quaternion	operator/ (R f) const
	divide by a real value

void	operator+= (R f)
	add a real value in place

void	operator-= (R f)
	subtract a real value in place

void	operator*= (R f)
	multiply for a real value in place

void	operator/= (R f)
	divide by a real value in place

const Quaternion	operator+ (const Quaternion &a) const
	sum two quaternions

const Quaternion	operator- (const Quaternion &a) const
	subtract two quaternions

void	operator+= (const Quaternion &a)
	add another quaternion in place

void	operator-= (const Quaternion &a)
	subtract a quaternion in place

void	operator*= (const Quaternion &a)
	multiplication from the right side

void	operator/= (const Quaternion &a)
	divide in place by another quaternion

const Quaternion	operator* (const Quaternion &a) const
	multiplication between quaternions

const Quaternion	operator/ (const Quaternion &a) const
	division between quaternions

R	normSqr () const
	extract the square of the norm, i.e. norm*norm

R	norm () const
	extract the norm

const Quaternion	normalized (R n=1.0) const
	return the normalized quaternion

void	normalize (R n=1.0)
	normalize in place

const Quaternion	conjugated () const
	conjugated quaternion +, -, -, -

void	conjugate ()
	conjugate in place +, -, -, -

const Quaternion	inverted () const
	inversed quaternion: 1/*this

void	inverse ()
	inverse in place

const Quaternion	opposed () const
	the opposed quaternion: -*this

void	oppose ()
	oppose in place

const Quaternion	squared () const
	this * this

void	square ()
	this = this * this

void	rightMult (const Quaternion &a)
	multiplication from the right side ( this <= this * a )

void	leftMult (const Quaternion &a)
	multiplication from the left side ( this <= a * this )

void	rightMult_fast (const Quaternion &a)
	multiplication from the right side, different implementation

void	leftMult_fast (const Quaternion &a)
	multiplication from the left side, different implementation

void	setMatrix3 (R m[9]) const
	generate the associated 3x3 rotation matrix, assuming norm(this)==1 More...

void	rotateVector (R des[3], const R src[3]) const
	Rotate a 3D vector: des = Q * src * Q.conjugated()

void	rotateVector (R v[3]) const
	Rotate V in place.

void	setFromMatrix3 (const R m[9])
	set from given rotation matrix

void	setOpenGLMatrix (float m[16], const float *trans=0) const
	generate OpenGL transformation matrix, translation followed by rotation

void	setOpenGLMatrix (double m[16], const double *trans=0) const
	generate OpenGL transformation matrix, translation followed by rotation

void	setFromPolar (const R v[4])
	set from polar coordinates (r, phi, theta, psi)

void	getPolar (R v[4]) const
	calculate the polar coordinates (r, phi, theta, psi)

void	setFromAxis (const R v[3])
	set as rotation of axis v, and angle = v.norm(); More...

void	setFromAxis (const R v[3], R angle)
	set as rotation of axis v, and angle 'angle' More...

void	setFromPrincipalAxis (int axis, R angle)
	set as rotation of angle 'angle' and axis X, Y or Z (axis=0,1,2) More...

R	getAngle () const
	return angle of the rotation

R	getAngle (R v[3]) const
	compute the axis and return the angle of the rotation

void	getAxis (R v[3]) const
	compute the axis and return the angle of the rotation

const Quaternion	scaledAngle (R s) const
	multiply the angle of the rotation by s

const Quaternion	slerp (const Quaternion &b, const R u) const
	Linear interpolation between rotations 'this' and 'b'.

void	print (FILE *out=stdout, bool parenthesis=false) const
	printf

void	println (FILE *out=stdout, bool parenthesis=false) const
	printf with a new-line

Static Public Member Functions
static const Quaternion	newFromPolar (const R v[4])
	return new quaternion with polar coordinates (r, phi, theta, psi)

Member Function Documentation

void setFromAxis ( const R v[3] )

inline

for small angles, we assume here angle ~ v.norm()

void setFromAxis	(	const R	v[3],
		R	angle
	)

inline

we normalize v for more security

void setFromPrincipalAxis	(	int	axis,
		R	angle
	)

inline

along one of the unit axis specified by 'axis': ( 0=x, 1=y, 2=z )

void setMatrix3 ( R m[9] ) const

inline

assumes that the quaternion is of norm = 1

Detailed Description

template<typename R> class Quaternion< R >

Public Member Functions

Static Public Member Functions

Member Function Documentation

template<typename R>
class Quaternion< R >